Contents

About X-Menu

Installing X-Menu

Removing X-Menu

Using X-Menu as the Shell

Scripts

@statements

$commands

*modifiers

Common Problems


About X-Menu
X-Menu, Version 2.0

Distribution

Changes

X-Menu is an application that can be used to replace the Task Manager for Windows 3.1. When X-Menu is installed, if the user double clicks the desktop, or types CTRL+ESC, a popup menu is displayed under the mouse’s pointer (or somewhere in the vicinity of the window that has the focus), rather than the Task Manager’s dialog box.

This menu is fully scriptable, so the user can switch to any of the currently running applications, start applications, open documents, or perform other commands (such as activate the screen saver, or exit Windows) that are built into X-Menu.

X-Menu requires a 386 or higher, and Microsoft Windows 3.1.

Avocado!, or Why A Double-Click?
X-Menu is activated by double-clicking upon the desktop rather than singlely-clicking upon the desktop for two reasons.

First, it is much easier to implement and far more stable. Windows already maps double-clicks in the desktop to a routine that starts an application (by default the Task Manager). To respond to a single click in the desktop, X-Menu would have to replace the window procedure for the desktop window — generally the more an application fiddles about with the operating system, the more likely it is to interfere with other applications that fiddle about with the operating system.

Second, the user accidentally clicks on the desktop far more often than he or she would realize. One often misses the sizing frame around windows when attempting to change a window’s size, and can even miss windows entirely when quickly switching between overlapping windows, or attempting to drag a window by the title bar. Use of a Macintosh (which will bring the Finder to the front if the user clicks on the desktop), indicates that it is exceptionally irritating to have a poorly placed mouse click suddenly switch applications, bring up a dialog box, or do anything else (this is my pet peeve with the Macintosh, its user interface is generally much better than Windows). A double-click is a much more deliberate action, and much more likely to be in the correct place. The user very quickly learns to double click without taking the time to think about it, much as he or she learns to select entire words by double clicking them.

If you none-the-less want X-Menu to respond to a single click in the desktop, you can use the Avocado! application (AVACADO.EXE), included with X-Menu. Avocado! does all the horrible (and potentially problematic) things required to convince Windows that a single click in the desktop is a double click, and undoes them when it exits. Simply place Avocado! in your startup group so it automatically starts when Windows starts the Program Manager.

NOTE: Avocado! seems to work perfectly fine, and seems to be perfectly well behaved. However, because it is an intrusive program that modifies the operating system, it may cause conflicts with other intrusive programs. X-Menu does not depend upon Avocado!, nor does Avocado! depend upon X-Menu; this keeps the potential source of incompatibilities completely contained within the optional Avocado!.


Distribution

X-Menu 2.0, along with Avocado! 1.0, is FreeWare: it is distributed as a fully functional application with no strategically missing features, nor any sickening pleas for money. It may be copied, distributed and used with wild abandon, provided that it is copied and distributed in its entirety, unchanged (obviously, no one cares if you only use one part of X-Menu, or modify your copy in some way).

If you use X-Menu, you are encouraged to send a postcard to me at the address below, especially if you have found any bugs, or have any suggestions for improvements (other than an installer program). Postcards allow me to estimate how many people use X-Menu, and whether further development is warranted.

X-Menu consists of the following four files:

XMENU.EXE

XMENU.HLP

AVOCADO.EXE

AVOCADO.WRI

If you have downloaded an incomplete version of X-Menu, please send hate mail to the operators of the bulletin board from which you downloaded it, berating them for their lack of diligence.

 Warranty Disclaimer
Robb Horn (The Author) makes no warranty of any kind,  expressed or implied, including any warranties of fitness for a particular purpose. In no event will the author be liable for any incidental or  consequential damages arising from the use of, or inability to use, this program.

Please send any comments and/or bug reports to:

Robb Horn
3165 St. Paul Blvd.
Rochester, NY 14617

Limits and Known Problems

•	Your menu may not contain more than 256 commands; menu items corresponding to additional commands are quietly dropped. Likewise, commands may be no more than 255 characters (I believe Windows sets a lower limit due to DOS), and menu text may be no more than 255 characters.

•	If your script file is greater than 10,000 bytes long, X-Menu will not attempt to load it, and will (quietly) use the default script instead.

•	If the auto-minimize feature is enabled, selecting the Script or Help buttons from the About dialog does not minimize the current application. X-Menu does this deliberately, so this is not actually a bug (although it could be mistaken for one), it is a feature based upon a careful consideration of the user interface.

•	The timeout value, specified via the @timeOut statement cannot be longer than 30 seconds. If it is specified as longer than 30 seconds, X-Menu will use 30 seconds.

•	The existence of @magic. The fact that this kludge is a configurable kludge does not mean that it is fine.

•	X-Menu help cannot be accessed by typing <F1> while the menu is displayed.

•	Installing X-Menu by hand can be slightly brutal for those users who are less comfortable with their computer. So can working with the script. An installation/removal program may eventually be developed to address the first problem, and a visual menu editor to address the second (although I would have to convince myself that the editor is easy and intuitive, and I’ve yet to see anything even slightly reasonable to pattern it upon)


Changes

Changes for Version 2.0

•	X-Menu now remains running at all times. This makes it more responsive to the user activating it (since it does not have to be read from the disk). This also fixes problems with applications that expect the application that launched them to remain running for a few moments (Symantec Execution Monitor is the only known example).

•	The tasks displayed in the menu may now be sorted and numbered. In addition, X-Menu may be left off the task list, and the currently running application’s menu item has a check mark by it.

•	By default, X-Menu now sets the current directory to be the directory that contains the application or file that it is opening. Previous versions of X-Menu always set the directory to be the Windows directory. The original behavior can be returned via the @windowsDir statement. Also, the current directory to be used can be specified explicitly in the command.

•	The About dialog (with the ever important copyright information), the Run dialog, the Program Manager and the File Manager are all accessible via the X-Menu icon’s menu, so the most basic commands are always accessible, even if the script has been mangled.

•	When X-Menu is activated via the keyboard, it will generally attempt to position the menu and dialog boxes somewhere in the vicinity of the center of the window you are using, rather than near the mouse.

•	A timeout value can now be specified via the @timeOut statement. This allows the user to specify a maximum amount of time that the popup menu will be displayed.

•	The $newScript and $oldScript commands have been added, to ease the management of script files. When a script is created, the user now has the option of choosing the name of the file; this fixes problems that occurred when XMENU.XMU already exists.

•	Since the About dialog box is now accessible via the X-Menu icon’s menu, the background menu does not have an about item forced upon it.

Changes for Version 1.1.1

•	Added more @statements, so it is never necessary to use a $command in the script file.

•	Added support for the tilde (~) as an escape character in menu scripts, allowing the use of special characters in commands and menu text.

Changes for Version 1.1

•	The original scripting language has been replaced with a far more regular and consistent language.

•	It is now possible to force the About dialog box to appear in the default colors.

•	Avocado!, a separate, optional application that makes Windows believe that a single click in the desktop is actually a double-click — which causes X-Menu to respond to a single click — is included.

•	The magic number used to calculate menu width (for positioning the menu) is now adjustable. This should ease interaction with strange applications and DLLs that modify the way Windows draws menus.

Changes for Version 1.0.1

•	X-Menu now properly handles applications that change the title of their main window while X-Menu’s menu is displayed (for example, a mouse odometer).

•	When activating an application, X-Menu will not restore the application’s main window if it was maximized. X-Menu also now sends a SC_RESTORE message rather than using ShowWindow; this is what the Task Manager does, and some applications depend upon this behavior.


Installing X-Menu

X-Menu does not have an installation program — it must be installed by hand, and this requires making changes to your SYSTEM.INI file (located in your Windows directory). This is really not as bad as it sounds, and is explained in detail below. Read (or at least skim) the directions before attempting to install.

•	Use the File Manager to move (or copy) the files XMENU.EXE and XMENU.HLP to your Windows directory.

•	Still using the file manager, select the file SYSTEM.INI. From the File menu, choose the Copy item. Copy SYSTEM.INI to SYSTEM.BAK, or something similar. If you make an error, you will want a copy of the original SYSTEM.INI file.

 •	From the Program Manager, select the Run item in the File menu. This will prompt you for a command line.

•	Type sysedit, and press return. This should start the System Configuration Editor, a text editor that automatically opens your AUTOEXEC.BAT, CONFIG.SYS, WIN.INI and SYSTEM.INI files. If you have removed SYSEDIT.EXE from your hard drive at some point, use Notepad to open your SYSTEM.INI file.

•	If you have not already done so, take a moment to examine the structure of the SYSTEM.INI file. It consists of two types of lines: section headings of the form [section], and variable assignments of the form variable=value. The *.INI files store settings and preferences for the system and applications.

•	Locate the taskman.exe= line in the [boot] section of the SYSTEM.INI file (capitalization may vary). This is where Windows stores the name of the Task Manager application.

•	Change this line to read:
taskman.exe=xmenu.exe
This will tell Windows to execute X-Menu rather than the Task Manager (If you have not followed the above directions exactly and have placed X-Menu’s files in a directory other than the Windows directory, you may have to specify where XMENU.EXE is located).

•	Restart Windows. Changes to the SYSTEM.INI file do not take effect until the next time Windows is run.


Removing X-Menu

•	Open your SYSTEM.INI file (located in your Windows directory), either with Notepad, or the System Configuration Editor (SYSEDIT).

•	Locate the taskman.exe= line in the [boot] section of your SYSTEM.INI file. This line should read:
taskman.exe=xmenu.exe
Or something similar.

•	Change this line to read:
taskman.exe=taskman.exe
This will make Windows execute the Task Manager application, rather than X-Menu.

•	Restart Windows (changes to the SYSTEM.INI file are not noticed until Windows restarts). Make sure that the Task Manager is functioning properly by double-clicking on the desktop. (If the Task Manager is not working properly, make sure that TASKMAN.EXE is located in your Windows directory).

•	At this point, you can safely delete the files XMENU.EXE, XMENU.HLP, XMENU.INI and XMENU.XMU. The last two files are created by X-Menu if you have changed your menu script.


Scripts

X-Menu’s menu is built from a script, either contained within X-Menu (if the user has not chosen to modify the script), or in a file most likely named XMENU.XMU (if the user has a custom script).

The default script (comments added):

;; comments start with a pair of semicolons

;; and extend to the end of the line

@about    ;; add about item

@separator  ;; add horizontal line

;; NOTE: Windows treats the & character in

;; menu items special — it makes the next

;; character a short cut key

&Managers

{

;; Begin a sub-menu

&Programs {progman.exe}

&Files {winfile.exe}

&Tasks {taskman.exe}

P&rinting {printman.exe}

@separator

&Control Panel {control.exe}

Setup {setup}

@separator { }

&DOS Prompt {dosprmpt.pif}

}

&Programs

{

Calculator {calc}

Character Map {charmap.exe}

Notepad {notepad}

Paint Brush {pbrush}

Write {write}

}

@separator

@tasks {!self}

@separator

@run

@screensaver

X-Menu’s scripting language has three types of statements: @statements, menu items, and sub-menus (also called popup menus).

An @statement is a directive to X-Menu to control how it builds the menu. If an @statement has any arguments, they follow the @keyword, enclosed in curly braces; if there are no arguments, the curly braces may be omitted. @statements are interpreted as X-Menu builds the menu. There may not be a space between the @ and the keyword.

A menu item consists of the menu text (the text that will appear in the menu), followed by the command that will be executed when (and if) the user chooses that menu item, enclosed in curly braces. The command is interpreted by X-Menu only when the menu item is chosen by the user; if there is an error in the command, X-Menu will display a dialog box when (and if) the menu item is chosen.

Special characters may be embedded within a chunk of text by preceding the special character with a tilde (~). Special characters that require this treatment would be: tabs, newlines, curly braces, leading @ symbols, and (of course) tildes. To enclose a pair of semicolons, place a tilde between the semicolons, so they are not interpreted as the start of a comment.

A sub-menu consists of the sub-menu’s title (which will appear in the parent menu), followed by an open curly brace, a list of statements to build the sub-menu, and a close curly brace.

X-Menu will strip excess whitespace (spaces, tabs, linefeeds, et cetera) from chunks of text (menu items and commands) as follows: leading and trailing whitespace is removed; whitespace between words is condensed to a single space. This allows statements to be on separate lines, and allows a sub-menu statement to be broken into several lines (perhaps one per menu item), and in general will prevent nasty characters from appearing in the menu.

A command (the text executed when a menu item is chosen) may be one of two things: a Windows command line (like those found in the Run and Properties dialog boxes of the Program Manager — often simply the name of a file or application); or, a X-Menu built-in command, which will start with a $.

If you want your command to automatically open an application or document in a particular state (minimized (iconic), normal, or maximized (zoomed)), you can include a *modifier at the beginning of the command. A command to open the application WeaselWorks™ could be:
*min: weasel.exe

If you want the current directory for a command to be something other than the default (where ever the application or file being opened is located), you can explicitly set the current directory by including it in double square brackets at the end of your command. The current directory is where the application will look for files, and where the Open... dialog box will initially be looking. As an example, if you wished to open the application WeaselWorks™ setting the current directory to be C:\DOCUMENT\S_THAT_I\LIKE, use the following:
weasel.exe [[C:\DOCUMENT\S_THAT_I\LIKE]]

Some applications will get confused if they require files in their own directory and they assume that the current directory is their own directory. Most applications do not make this assumption.

 @statements, $commands and *modifiers are identified by the first three letters, with upper and lower case letters being treated the same. Thus, @about, @ABO, and @abomination are all the same.

@statements

$commands

*modifiers

Common Problems


@statements

An @statement is a directive to X-Menu to control how it builds the menu. If an @statement has any arguments, they follow the @keyword, enclosed in curly braces; if there are no arguments, the curly braces may be omitted. @statements are interpreted as X-Menu builds the menu. There may not be a space between the @ and the keyword.

For almost every $command, there is a corresponding @statement, since the use of both $commands and @statements has been found to be cumbersome, if not actually confusing. Because @statements are interpreted while the menu is being built, this also allows special handling of some menu items (such as dimming the item for the screen saver if there is no screen saver chosen.)

@about {about, color, help, script}
Adds the “About X-Menu 2.0...” item to the menu, and/or adjusts flags that affect how the About dialog box is displayed.

The @about statement recognizes four flags: about, which causes the about menu item to be added to the background menu; color, which causes the About dialog to be drawn in non-default colors (nothing exciting though); help, which makes the Help button visible, and script, which makes the script button visible. By default, each of these flags is turned on — flags can be turned off by preceding them with an exclamation point.

Example: to remove the Script button from the About dialog box, without adding an about item to the background menu, you would need to add the following line to your script:
@about {!about, !script}

@autoMin { arg }
The @autoMin statement is used to control the auto-minimize feature of X-Menu. When this feature is enabled, X-Menu will minimize the current application when it switches to (or starts) another application, reducing desktop clutter. By default, the auto-minimize feature is turned off.

If arg is a negative integer, this statement will turn off the auto-minimize feature. If arg is a positive integer, this statement will turn on the auto-minimize feature. On all other cases, this statement adds a menu item that enables the user to toggle the auto-minimize feature on and off, checking the item as required. The menu item text in this case is either arg, or a default string if arg is empty.

@editScript {text}
Inserts a menu item to edit the script file. The menu text is text, if specified, or a default string. This statement uses the $editScript command, which can be disabled in the @about statement.

@exitWindows {text}
Inserts a menu item to exit Windows (posting a dialog first, confirming the users intention). The menu text is text, if specified, or a default string.

@help {text}
Inserts a menu item to display the help file. The menu text is text, if specified, or a default string. This statement uses the $help command, which can be disabled in the @about statement.

@magic {int}
X-Menu estimates the width of the menu (for placement purposes) to be the width of the longest text within the menu, plus a constant (padding on either side of the string, the black outline, that little arrow that signals a sub-menu). X-Menu guesses the value of this constant to be 35 (determined through empirical testing on my computer). If the menu is shifted too far to the left when the mouse is near the right edge of the screen, you may need to increase this magic number. Because this statement does not create any menu items, it may appear anywhere within the script.

Yes, this is a kludge, but it’s an adjustable kludge.

@minimizeOthers {text}
Inserts a menu item to minimize all applications except the currently executing application. The menu item’s text is text, if specified, or a default string.

@notepad {editor}
By default, X-Menu will use Notepad to open the menu script. If you despise Notepad, you can use this statement to specify another text editor. This cannot by Write or another word processor, since they add strange formatting characters.

Sample: To use WeaselWorks™, with the text only flag, you would need to add the following statement to your script:
@notepad {weasel /t}

@reboot {text}
Inserts a menu item to reboot the computer (posting a dialog first, confirming the users intention). The menu text is text, if specified, or a default string.

@restartWindows {text}
Inserts a menu item to restart Windows (posting a dialog first, confirming the users intention). The menu text is text, if specified, or a default string.

@run {text}
Inserts a menu item to display the Run dialog box, which is very similar to the Run dialog box in the Program Manager. The menu text is text, if specified, or a default string.

@screenSaver {text}
Inserts a menu item (with menu text text, if specified, or a default string), that will activate the screen saver when chosen. The menu item is dimmed if the user has not activated a screen saver via the Control Panel.

@separator
Inserts a separator into the menu.

@startup {command}
If X-Menu is run as the shell application, rather than building and displaying the menu, it will execute any commands specified in @startup statements.  @startup statements are ignored when X-Menu is run normally. There may be more than one @startup statement, and they may appear anywhere within the script.

@tasks {check, !number, self, !sort}
Inserts one menu item for each currently running application, using the title of the application’s main window as the menu text. Choosing any of these items causes the application’s main window to be selected, restoring the window, if it was minimized.

The @tasks statement recognizes four flags: check, which adds a check mark next to the item for the currently running application; sort, which sorts the tasks alphabetically; number, which adds a decimal shortcut key for the first 9 tasks; and self, which leaves X-Menu in the task list. By default, sort and number are turned off, while check and self is turned on.

@timeOut {arg}
Specifies the approximate maximum time that X-Menu’s popup menu will be displayed. If arg is a positive integer, the menu will be displayed for no more than roughly arg seconds. Otherwise, the menu will be displayed indefinitely. The default setting is 30 seconds. A limitation in this version of X-Menu makes 30 seconds the maximum timeout value, any value larger than 30 seconds will be treated as 30 seconds.

@windowsDir {arg}
Earlier versions of X-Menu failed to properly set the current directory when opening files and applications; it would often set the current directory to the Windows directory, which could cause problems. X-Menu 2.0 fixes this bug. If, however, you like this bug for some reason, you can reintroduce it by adding this statement to your script (anywhere), and making arg a non-zero integer (such as one (1)).


commands
$commands

A $command is a command built into X-Menu. $commands are useful for performing relatively trivial tasks for which it would be impractical to have a stand alone application, or changing X-Menu’s settings.

Nearly every $command has a corresponding @statement, which creates a menu item using the $command. Using both @statements and $commands together has been found to be cumbersome, if not actually confusing, so additional @statements were added to make it possible to never use a $command directly.

The only exception to the above are the $newScript and the $oldScript commands, which should seldom be used, and likely not included in a menu.

$about
Displays the About dialog box. This command is used by the @about statement.

$automintoggle
Toggles the flag in the XMENU.INI file for the auto-minimize feature. This flag is only used if the menu script has a @automin statement that does not force the feature on or off. The @automin statement uses this command; it is doubtful that you would ever need to use it directly.

$editScript
Opens the script file using Notepad, or the editor specified using the @notepad statement. If there is no script file, X-Menu will attempt to create one with the default script.

$exitWindows
Exits Windows, after first displaying a dialog box confirming the user’s intent.

$help
Displays this help file.

$minimizeOthers
Minimize all other applications, except the one that you are currently working with.

$newScript
Create and edit a new script file, selecting the name via the standard save file dialog box, and editing it with the current script editor (which may be changed via the @notepad statement in the X-Menu script). This script is initially the default script.

$oldScript
Switch scripts to an old script file, chosen using the standard open file dialog box.

$reboot
Reboots the computer (after a dialog box to confirm).

$restartWindows
Restarts Windows (after a dialog box). This is useful only on the rare occasions when the user has modified the SYSTEM.INI file, and needs to restart Windows for the changes to take effect.

$run
Displays the Run dialog box, allowing the user to either type the desired command, or browse the disks looking for the application or document that catches his or her fancy at the moment.

$screenSaver
Activates the screen saver, if the user has selected one in the Desktop control panel. It is preferable to use the @screenSaver command, rather than creating a menu item with this command, as the @screenSaver statement will dim the menu item if there is no screen saver selected in the Desktop control panel.


*modifiers

By itself, a Windows command line does not specify how an application should be opened (minimized, normal, or maximized). As X-Menu prepares to execute a command, it first checks to see if the command is preceded by a *modifier, which can be used to request how an application or document should be opened (this request is passed to the application, which my or may not honor it).

*modifiers add the functionality of the Window State radio buttons in the Run dialog box to commands within the menu script.

The format of a command with a *modifier is as follows:
*modifier: command
Where modifier is one of the following: minimize, normal, or maximize. The modifiers are case insensitive, and may be abbreviated by their first three letters.


Scripts: Common Problems

•	X-Menu does not handle errors in the script very gracefully; it never attempts to alert the user to an error, acting under the assumption that the user will notice a mangled menu. When it encounters an error, X-Menu skips all input up to the next closing curly brace. If your menu is missing items, you likely have an error in the statement corresponding to the first missing item.

•	Statements can sometimes appear to be inadvertantly combined. X-Menu’s scripting language does not recognize the end of a line as being the end of a statement, nor does it have any other way of explicitly separating statements (such as semicolons). This allows the user a great deal of freedom, and only occasionally comes back to bite. It can hide little errors and compound other errors.

A few general rules help fix these situations:

•	If the statment begins with an @command, and the next word is not a open curly brace, the statement ends immediately after the @command.

•	If the statement begins with an @command followed by an opening curly brace, the statement ends immediately after the next closing curly brace.

•	If the statement is a simple menu item, the statement ends immediately after the next closing curly brace.

•	If the statement is a popup menu, the statement ends immediately after the matching closing curly brace (this means that a popup menu statement may (and should) contain other statements).

•	An @command within a chunk of text (even if it appears on the next line) is merely part of that chunk of text. (The @ character is only special at the beginning of a chunk of text)

•	@statements must NEVER have spaces within them.

A friend of mine, with the unfortunate name of I. Offen-Chung, had the following in her script, which caused a great deal of confusion:

@minimize Others
@help {Help}

X-Menu interpreted these two statements not as @minimize Others and @help {Help}, but rather as @minimize and Others @help {Help}.

The intended help @command became part of a normal menu statement, which ran the application HELP.EXE, the MS-DOS help system, when chosen.


Using X-Menu as the Shell

If you find yourself opening most of your documents and applications through X-Menu, rather than through the Program Manager, you may want to get rid of the Program Manager entirely, which will free up the memory and resources used by the Program Manager for use by your other applications.

Background Information
When Windows starts, it automatically opens an application noted in the SYSTEM.INI file as the shell. By default, this is the Program Manager.

When the Program Manager starts (if it is the shell), it opens all of the items located in the Startup group, or at least tries to.

When there are no more applications running, Windows exits, returning the user to the cold, harsh reality of a MS-DOS prompt and the sinking feeling that he or she should have purchased a Macintosh (the PowerPC based ones are really nice, and offer better performance than a Pentium based IBM compatible, at a lower price; also, PowerPC native software is readily available now). Generally the user does not see this, since the Program Manager will exit Windows as it exits (but only if the Program Manager is the shell application).

Using X-Menu
If X-Menu is run as the shell, it will execute commands in @startup statements within its script (@startup statements are special @statements that are ignored when X-Menu is run as the task manager).

Should X-Menu be run as the shell, and there be no @startup statements, or should all the @startup statements fail to successfully start an application, X-Menu will start the Program Manager.

Because X-Menu is still installed as a replacement for the Task Manager, you can still access X-Menu and use it to open additional applications and documents. Do NOT install X-Menu as the shell without first installing it as the Task Manager, or you will not be able to use X-Menu to open applications and documents.

As an example, if you wanted to open the clock (minimized) and WeaselWorks™ (with the ever important Ferret option) when Windows starts, you would need to add the following to your X-Menu script:
@startup {*min: clock}
@startup {*norm: C:\WEASELS\WEASELS.EXE /F}

Installing
This assumes that you have already installed X-Menu as a replacement for the Task Manager. The SYSTEM.INI file (located within your Windows directory) contains (in the [boot] section) a line that should read:
shell=PROGMAN.EXE

You need to change this line to read:
shell=xmenu

If X-Menu is not located within your Windows directory, you may have to be much more specific.

Information on editing the SYSTEM.INI file is located in Installing X-Menu, refer to that section if you need the details.